---
title: Migrating from Docusaurus
description: Tips for migrating an existing Docusaurus project to Astro
type: migration
stub: true
framework: Docusaurus
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

[Docusaurus](https://Docusaurus.io) is a popular documentation website builder built on React.


## Key Similarities between Docusaurus and Astro

Docusaurus and Astro share some similarities that will help you migrate your project:

- Both Astro and Docusaurus are modern, JavaScript-based (Jamstack) site builders intended for [content-driven websites](/en/concepts/why-astro/#content-driven), like documentation sites. 

- Both Astro and Docusaurus support [MDX pages](/en/guides/markdown-content/). You should be able to use your existing `.mdx` files to Astro.

- Both Astro and Docusaurus use [file-based routing](/en/guides/routing/) to generate page routes automatically for any MDX file located in `src/pages`. Using Astro's file structure for your existing content and when adding new pages should feel familiar.

- Astro has an [official integration for using React components](/en/guides/integrations-guide/react/). Note that in Astro, React files **must** have a `.jsx` or `.tsx` extension.

- Astro supports [installing NPM packages](/en/guides/imports/#npm-packages), including several for React. You may be able to keep some or all of your existing React components and dependencies.

- [Astro's JSX-like syntax](/en/basics/astro-components/#the-component-template) should feel familiar if you are used to writing React.


## Key Differences between Docusaurus and Astro

When you rebuild your Docusaurus site in Astro, you will notice some important differences:

- Docusaurus is a React-based single-page application (SPA). Astro sites are multi-page apps built using [`.astro` components](/en/basics/astro-components/), but can also support [React, Preact, Vue.js, Svelte, SolidJS, AlpineJS, Lit](/en/guides/framework-components/) and raw HTML templating.

- Docusaurus was designed to build documentation websites and has some built-in, documentation-specific website features that you would have to build yourself in Astro. Instead, Astro offers some of these features through [Starlight: an official docs theme](https://starlight.astro.build). This website was the inspiration for Starlight, and now runs on it! You can also find more [community docs themes](https://astro.build/themes?search=&categories%5B%5D=docs) with built-in features in our Themes Showcase.

- Docusaurus sites use MDX pages for content. Astro's docs theme uses Markdown (`.md`) files by default and does not require you to use MDX. You can optionally [install Astro's MDX integration](/en/guides/integrations-guide/mdx/) (included in our Starlight theme by default) and use `.mdx` files in addition to standard Markdown files.


## Switch from Docusaurus to Astro

To convert a Docusaurus documentation site to Astro, start with our official [Starlight docs theme starter template](https://starlight.astro.build), or explore more community docs themes in our [theme showcase](https://astro.build/themes?search=&categories%5B%5D=docs). 

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install/auto/#starter-templates).

  <PackageManagerTabs>
    <Fragment slot="npm">
    ```shell
    npm create astro@latest -- --template starlight
    ```
    </Fragment>
    <Fragment slot="pnpm">
    ```shell
    pnpm create astro@latest --template starlight
    ```
    </Fragment>
    <Fragment slot="yarn">
    ```shell
    yarn create astro --template starlight
    ```
    </Fragment>
  </PackageManagerTabs>

Astro's MDX integration is included by default, so you can [bring your existing content files to Starlight](https://starlight.astro.build/getting-started/#add-content) right away.

You can find Astro's docs starter, and other official templates, on [astro.new](https://astro.new). You'll find a link to each project's GitHub repository, as well as one-click links to open a working project in StackBlitz, CodeSandbox and Gitpod online development environments.

## Community Resources

- Add your own!
